This is a beginner-friendly guide to the official Django Rest Framework tutorial that works for both Windows and macOS. If you have struggled to complete the official tutorial on your own, consider this guide a good place to start instead.

The final code is exactly the same and is available on GitHub. However I provide more detailed explanations of each step, use the Django admin rather than the Django shell for populating the models, emphasize class-based views over function-based views, and so on.

After you complete this tutorial, the official tutorial should make more sense and help you fully take advantage of the awesomeness that is the Django REST Framework.

NOTE: If you'd like to learn even more about APIs in Django, I've written an entire book on the subject, Django for APIs. The first few chapters are available for free.

You will need to have the latest version of Python installed on your computer. If you need help with this, go to Chapter 1: Set Up of the Django for APIs book for a step-by-step guide to configuring your computer for Django development.

Once that's done, create a dedicated directory for our code and set up a new Python virtual environment. This can live anywhere on your computer but in an easily accessible location. One option is the Desktop, whether you are on a Windows or Mac computer. That's what we'll do here.

Enter the following commands in your terminal:

Then, within the new directory, install django, djangorestframework, and pygments (which is used for code highlighting). Once all three packages are installed, make sure to activate the virtual environment shell.

If you use the command pip freeze to output the virtual environment, you should see the following:

Our new project is called tutorial, and within it, there is an app called snippets for our web API. Adding a period . at the end of the command is optional but recommended as otherwise Django will create an additional directory with the startproject command.

Now add the snippets app and rest_framework to the INSTALLED_APPS config in our tutorial/settings.py file. It's not enough to simply create new apps; they must also be explicitly added to INSTALLED_APPS.

The model is a good place to start any new project. In the snippets/models.py file, create a new model called Snippet.

Then create an initial migration file and sync the database for the first time.

We need to add some data to our model to make it "real" now. At this point, the official tutorial goes on a lengthy tangent into the Django shell. However, to beginners鈥攁nd even professional programmers鈥攖he graphical Django admin is often a more intuitive approach. That's what we'll use here.

But first, we need to update snippets/admin.py so the app will actually appear! Just as with the INSTALLED_APPS setting, apps must be explicitly added to the admin.

Now, create a superuser account to log in. Follow the prompts for setting a username, email, and password. I've used admin, ' [email protected], andtestpass123`.

And start our local web server for the first time.

Navigate over to the Django homepage at http://127.0.0.1:8000/ to confirm everything is working.

Then switch over to the Django admin at http://127.0.0.1:8000/admin/. Log in with your superuser account.

Click on the "+ Add" button next to Snippets. And create two new snippets.

Click the "Save" button in the lower right for each snippet. Both will be visible on the main Snippets page.

A Serializer transforms model instances into JSON. This is the real "magic" that Django Rest Framework provides for us. Consider that the end result of a traditional website is a page of HTML, CSS, and content from the database. But an API doesn't care about that: it's only raw data at endpoints, which means JSON and accompanying HTTP verbs that tell the API what actions can be taken (more on this shortly).

Create a new snippets/serializers.py file and update it as follows. We can extend DRF's ModelSerializer to create a SnippetSerializer class that uses our model and outputs the table fields.

Next, we need a view that handles the logic of combining a model, serializer, and, eventually, URL together. Just as traditional Django ships with several class-based generic views to handle common functionality, so too does Django Rest Framework have its own set of powerful class-based generic views we can use.

Specifically we will use ListCreateAPIView to create a read-write endpoint that lists all available Snippet instances and then RetrieveUpdateDestroyAPIView for a read-write-delete endpoint for each individual Snippet.

The final step is to configure our URLs. In the topmost, project-level tutorial/urls.py file, add include as an import for the snippets app URLs which will appear at the empty string ''.

Then create a snippets/urls.py file and add the following code.

Including format_suffix_patterns is an optional choice that provides a simple, DRY way to refer to a specific file format for a URL endpoint. It means our API will be able to handle URls such as http://example.com/api/items/4.json rather than just http://example.com/api/items/4.

Django Rest Framework ships with a browsable API that we can now use. Make sure the local server is running.

Navigate to the Snippets List endpoint at http://127.0.0.1:8000/snippets/.

We can also go to the detail view for each snippet. For example, the first snippet is at http://127.0.0.1:8000/snippets/1/.

As a reminder, the id is automatically set by Django on each database entry.

Currently our API has no restrictions on who can edit or delete code snippets. In this section we will make sure that:

First up let's add two fields to our existing Snippet model class: owner which will represent the user who created the code snippet and highlighted to store the highlighted HTML representation of the code.

We also want to ensure that when the model is saved, we use the pygments code highlighting library to populate our highlighted field. So we'll need some additional imports as well as a .save() method.

Normally we would create a migration and sync it to update our database tables. However since we have added an owner here and have existing content, it's simpler to just delete the database and start again. Make sure you have stopped the local server with Control+c.

Re-create our steps from earlier to create a new superuser account. We'll want a second superuser account which is simplest to setup from the command line too. So run createsuperuser twice. I've called my users admin and testuser. Then start up the local server.

Go back into the Django admin at http://127.0.0.1:8000/admin/ and login with the admin account.

If you click on the Users link you will be redirected to the Users page which should show both users.

Once complete, you should see the two users on the Users page.

We need to recreate our snippets too since the initial database was just destroyed. Create a new snippet and specify the Owner as one of our users. I've chosen testuser here.

But there's a problem when we try to "Save".

We are getting a ValidationError here. In the official tutorial the Django shell is used to input data, but we are using the admin here. So the existing code doesn't work as is. Recall that the highlighted field is automatically set by our custom save() method on the model, but the admin doesn't know this. It expects us to enter in a value here. To solve the problem update our admin.py file and set highlighted as a read-only field.

Try clicking the "Save" button again. It should work.

The final step is to click the Log out link in the upper right corner of the admin page.

We will shortly be adding permissions to our API so that only authenticated (logged-in) users have access.

Now that we have some users to work with, let's add endpoints for them to our API. Add a new UserSerializer class to the snippets/serializers.py file.

Because snippets is a reverse relationship on the default Django User model, it will not be included by default using the ModelSerializer class, we need to add an explicit field for it.

We also need to add two new read-only views for a list of all users and a detail view of individual users. Note that we use the generic class-based RetrieveAPIView for the read-only detail view. And that we import both User and UserSerializer at the top.

Finally we need to add the new views to the API by configuring their URL routes. Add the following pattern to snippets/urls.py.

Currently there is no way to automatically associate the logged-in user that created a snippet with the snippet instance. We can set this automatically by overriding .perform_create() method on our snippet views that lets us modify how an instance is saved.

Add the following method to our existing SnippetList view class.

Now that snippets are associated with the user that created them, let's update SnippetSerializer with an owner to reflect that. Make sure to also include owner in the list of fields too.

The source argument used here controls which attribute is used to populate a field and can point to any attribute on the serialized instance. Also note that we're using ReadOnlyField which is always read-only; it can not be used for updating model instances when they are serialized. We could have also used CharField(read_only=True) here to accomplish the same thing.

Now that code snippets are associated with users, we want to make sure that only authenticated users are able to create, update, and delete code snippets.

Django Rest Framework ships with a number of permission classes we could use to restrict access to a given view. Here we will use IsAuthenticatedOrReadOnly to ensure that authenticated requests have read-write access and unauthenticated requests only have read-only access.

Now navigate to our browsable API at http://127.0.0.1:8000/snippets/.

Since we are logged out, notice that you are no longer able to create new code snippets. In order to do so you need to be logged in as a user.

We can add a login view to the browsable API by editing the URLconf in our project-level tutorial/urls.py file. Add rest_framework.urls to the route api-auth/.

Note that the actual route used does not matter. Instead of api-auth/ we could also have used something-else/. The important thing is that rest_framework.urls was included.

Now open up the browser again and refresh the page. You will see a Log in link in the top right of the page.

Log in with your testuser account. Then navigate to our http://127.0.0.1:8000/users/ endpoint and notice that snipped ids are associated with each user, as desired.

We only have one snippet, made with our testuser account and containing the primary id of 1. If we added additional snippets for each user, they'd appear here as well. So things are working.

Really what we'd like is for all code snippets to be visible to anyone, but only the user that created a code snippet can update or delete it.

Django Rest Framework gives us several options for setting permissions: at a project-level, view level, or object level. In this case we will implement the last option and create a custom permission we can add to our SnippetDetail view class.

Create a new snippets/permissions.py file and then add the following code which extends Django Rest Framework's existing permissions classes.

Next add the new custom permission to SnippetDetail by importing it at the top and including it in permission_classes.

If you open the browser again to http://127.0.0.1:8000/snippets/1/ you will find that the 'DELETE' and 'PUT' actions appear on the snippet instance endpoint because we're logged in as testuser, the owner of the snippet.

Now log out and log in with the admin account. The DELETE and PUT options are not available. Good, as expected.

Currently there are endpoints for snippets and users, but we don't have a single entry point to our API. To create one, we'll use a regular function-based view and Django REST Framework's built-in @api_view decorator.

In snippets/views.py import api_view, Response, and reverse. Then use @api_view to set a GET for api_root.

Next we need to add a URL at the empty string "" for api_root. And since we're using reverse we also must add named urls to each existing view.

Now navigate to http://127.0.0.1:8000/ to see our new API Root page.

It lists both users and snippets as well as their respective API endpoints which can be clicked on.

The other obvious thing that's still missing from our pastebin API is the code highlighting endpoints.

Unlike all our other API endpoints, we don't want to use JSON, but instead just present an HTML representation. REST framework has two HTML renderers: one for dealing with HTML rendered using templates and one for pre-rendered HTML (which is our case here).

Also, there's no existing generic view that will work so we'll need to create our own .get() method.

In your snippets/views.py import renderers at the top and then create a new class for SnippetHighlight.

Add the new view to the urls file. Make sure to include the name snippet-highlight!

We only have one snippet in our database so the highlight will be located at http://127.0.0.1:8000/snippets/1/highlight/.

One of the more challenging aspects of web API design is dealing with the relationships between entities. We could use primary key, hyperlinks, slugs, strings, nesting, or a custom representation.

REST framework supports all of these styles but here we'll use a hyperlinked style between entities. In order to do so, we'll modify our serializers to extend HyperlinkedModelSerializer instead of the existing ModelSerializer.

The HyperlinkedModelSerializer has the following differences from ModelSerializer:

Let's rewrite our existing serializers to use hyperlinks.

Aside from swapping in HyperlinkedModelSerializer there is a new highlight field for snippets that points to the snippet-highlight url pattern, instead of the snippet-detail url pattern.

Also for the fields we add url to both and highlight to the snippet serializer.

Currently we only have the one code snippet but as others are added it makes sense to limit the number of snippets displayed per API endpoint. Let's paginate the results so that API clients can step through each of the individual pages.

REST Framework ships with a number of default settings which can be easily customized. We'll set a DEFAULT_PAGINATION_CLASS and PAGE_SIZE to 10 although we could easily customize things further as desired.

At the bottom of the tutorial/settings.py file add the following:

At this point it's possible to click around the entire API just via links. Success!

Section 6 of the official tutorial has us switch over from views and URLs to viewsets and routers. This is an optional choice that is, in my opinion, better suited to larger API projects and for developers already comfortable with REST framework. Since neither applies here we will not update our code. The resulting API endpoints will still be exactly the same!

With an incredibly small amount of code, we've now got a complete pastebin Web API, which is fully web browsable, includes a schema-driven client library, and comes complete with authentication, per-object permissions, and multiple renderer formats.

We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views.

You can review the final tutorial code on GitHub.

And if you'd like to learn even more about APIs in Django, check out my book Django for APIs.